Skip to content

Docs: describe what Superhero offers, for the outside reader - #3

Open
Jeanclaudeaoun wants to merge 7 commits into
mainfrom
claude/docs-positive-final-scan
Open

Jeanclaudeaoun wants to merge 7 commits into
mainfrom
claude/docs-positive-final-scan

Conversation

@Jeanclaudeaoun

Copy link
Copy Markdown
Contributor

What this does

A final pass over all 152 pages for the outside reader: our community of developers, other developers and other companies. Every page now says what Superhero offers and how to use it. The rules come from the edits already made on main (commit 3417126) and are applied across the tree:

  • What to do, not what we lack. "There is no X / you cannot Y / this is not yet Z" is rewritten as the thing the reader should do, or removed when there is nothing to do.
  • Permanence as ownership and verifiability. Posts, votes and events are "owned by the author, verifiable by anyone, stay on chain" rather than "cannot be deleted".
  • No variable cost figures. Gas amounts ("roughly 0.02 AE", "pays gas only") are gone. Protocol constants stay: 1% spread, 0.5% affiliation fee, 555 AE vote contribution, 0.001 AE invite floor, curve parameters, 55% / 10% thresholds, key-block periods.
  • No internals the reader cannot act on. Retry counts, polling intervals, Redis fallbacks, in-memory caps, debug endpoints.
  • Em dashes replaced with colons or commas in prose (kept inside code blocks).

Lint: python3 scripts/lint-mdx.py → 0 issues across 152 pages. corepack pnpm build passes. out/ added to .gitignore.

Things to look at

These are the edits that change more than tone. Each one is easy to revert on its own.

Page Change
contracts/security.mdx, tokens/risks.mdx The line "The contracts have not undergone a third-party security audit" is removed. If you want it kept, the neutral form would be "The contracts are open source; an independent audit report will be linked here when published."
tokens/risks.mdx Retitled Before You Trade (also in _meta.json and the 14 pages linking to it). Rewritten as what to check and how the curve, spread and slippage work.
dao/protocol-dao.mdx "Issuance is live; the governance it is named after is not yet built" and the "What does not exist yet" section are removed. The page now describes the token's properties and its intended use (platform-wide governance, proposal voting, staking), and how it sits next to the two live voting systems.
wallets/web-wallet.mdx The extension-vs-web trade-off table is removed; each wallet page says what that wallet is for.
rewards/rewards-program.mdx The "Under 100 followers / Not eligible" row is removed; eligibility is described as steps.
api-reference/transactions.mdx, api-reference/index.mdx, tokens/transactions.mdx GET /api/debug/failed-transactions removed. GET /api/transactions/by-hash is the documented way to pull a mined trade into the index.
api-reference/conventions.mdx The sentence about Swagger being off in production is removed.
Testnet cells (api-reference, concepts, getting-started, aeternity, resources) "Run your own from superhero-api" instead of a host we do not run.
defi/* Copy only. Swap, pools, bridge and wrapped-AE pages describe the flows; no code or figures changed.
governance/polls.mdx, governance/registry.mdx "If one host does not answer, try the other" removed; both governance-server hostnames stay documented.
social/chat.mdx "What chat is not" → "Chat and the on-chain record": the same facts (relay holds membership and history, DMs NIP-04, room messages readable by members) as a posts-vs-chat comparison.

Section headings renamed to match: "Nothing is locked" → "Your AE stays liquid", "The 555 AE is not refundable" → "The 555 AE contribution", "What moderation cannot do" → "The scope of a mute", "Not the same thing as a community DAO" → "Governance polls and community DAOs", and a few more of the same shape.

Commits

One commit per section so each can be reviewed on its own: api-reference; agents; concepts + getting-started + æternity + contracts; wallets; tokens + defi; rewards + identity + resources + SECURITY.md; social + dao + governance.

🤖 Generated with Claude Code

https://claude.ai/code/session_018Az8TKjLpFXw9ouAdoyLDs


Generated by Claude Code

claude added 7 commits October 9, 2026 19:47
…acks

Rewrites the API reference pages for an outside developer: every "there
is no X" and "not emitted, do not build on it" becomes the thing to use
instead, cost estimates become "pays gas at the network's current gas
price", and the "legacy" labels on live fields are gone. The debug
failed-transactions endpoint and the non-production Swagger note are
removed; both are operator internals.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018Az8TKjLpFXw9ouAdoyLDs
… well

Every "the skill has no X" and "cannot be undone" becomes the thing to do
instead, with the safety guidance kept: funding is the loss ceiling,
transactions are final once mined, exits run on the cycle. The remaining
gas estimate on the token-creation page is replaced with "paid at the
network's current gas price". Headings now name the reader's action:
"Hard boundaries", "Before you trade", "What moves with rotation".

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018Az8TKjLpFXw9ouAdoyLDs
…de reader

Every page in these sections now says what Superhero and the chain offer
and how to use them. "There is no X" becomes the thing to do, permanence
is presented as ownership and verifiability, "what Superhero does not
use" becomes "other protocol features", and estimated gas figures (the
worked gas example, the measured redemption cost, approximation-error
measurements) are gone in favour of "pays gas at the network's current
gas price". Protocol constants, skill balance checks and safety guidance
for the reader's own keys stay.

The testnet API cells no longer read "not publicly documented": they
point to running the API from the public superhero-api repository.
README now names the pages' "Related" section correctly, and the static
export folder is ignored.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018Az8TKjLpFXw9ouAdoyLDs
…it safe

- Describe the built-in wallet, extension and mobile wallet by their
  strengths and the steps to set them up, back them up and connect.
- Rename the site-data section to 'Site data and your backup' and point
  the troubleshooting and create-account anchors at it.
- Drop the extension-vs-web trade-off table; each page now says what
  that wallet is for.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018Az8TKjLpFXw9ouAdoyLDs
…ide reader

- Rewrite tokens/risks as 'Before You Trade': what to check and how the
  curve, spread and slippage work, instead of a list of pathologies.
- Rename the page in _meta.json and update every link text to it.
- Remove the debug-endpoint section from tokens/transactions; the
  by-hash endpoint is the documented way to pull a mined trade in.
- Keep protocol constants (1% spread, curve parameters); drop variable
  gas and cost figures across the DeFi pages.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018Az8TKjLpFXw9ouAdoyLDs
…k gives

- Rewards: eligibility and claiming described as steps; the
  'not eligible' row and internal thresholds removed.
- Identity: chain names, address links and X verification described by
  what the reader gets and how to set them up.
- Resources: testnet cell points at running superhero-api; brand and
  support pages trimmed to what an integrator needs.
- SECURITY.md: a reporting policy, written for the reporter.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018Az8TKjLpFXw9ouAdoyLDs
… to use it

- Social: posts framed as owned, verifiable on-chain records; chat as the
  realtime layer next to them; moderation as membership control; the
  internal retry/polling details the reader cannot act on removed.
- DAO: the 555 AE framed as a contribution to the treasury; proposals,
  voting and ChangeDAO written as steps and checks for the voter;
  ProtocolDAO described by its properties and intended use.
- Governance: polls, delegation and the registry described by what they
  record and how to use them; variable gas cost figures removed.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018Az8TKjLpFXw9ouAdoyLDs

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants